home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume2 / util / suplib.dcs < prev    next >
Internet Message Format  |  1988-10-22  |  26KB
  1. Path: xanth!nic.MR.NET!hal!cwjcc!mailrus!uflorida!gatech!bbn!ulowell!page
  2. From: page@swan.ulowell.edu (Bob Page)
  3. Newsgroups: comp.sources.amiga
  4. Subject: v02i007:  suplib-docs - documentation for Matt's support library
  5. Message-ID: <9769@swan.ulowell.edu>
  6. Date: 22 Oct 88 04:16:24 GMT
  7. Organization: University of Lowell, Computer Science Dept.
  8. Lines: 781
  9. Approved: page@swan.ulowell.edu
  10.  
  11. Submitted-by: dillon@cory.berkeley.edu (Matt Dillon)
  12. Posting-number: Volume 2, Issue 7
  13. Archive-name: util/suplib.docs
  14.  
  15. [Matt sent 2 DISKS full of stuff ... my first week on the job! :-) ..Bob]
  16.  
  17. # This is a shell archive.  Remove anything before this line
  18. # then unpack it by saving it in a file and typing "sh file"
  19. # (Files unpacked will be owned by you and have default permissions).
  20. # This archive contains the following files:
  21. #    ./dio.doc
  22. #    ./qint.doc
  23. #    ./summary.doc
  24. #    ./suplib.doc
  25. #
  26. if `test ! -s ./dio.doc`
  27. then
  28. echo "writing ./dio.doc"
  29. cat > ./dio.doc << '\Rogue\Monster\'
  30.  
  31.                     DIO
  32.  
  33.     EXEC device driver IO support routines... makes everything easy.
  34.  
  35.     dfd = dio_open(name, unit, flags, req/NULL)
  36.  
  37.       open an IO device.  Note: in some cases you might have to provide a
  38.       request structure with some fields initialized (example, the console
  39.       device requires certain fields to be initialized).  For instance, if
  40.       openning the SERIAL.DEVICE, you would want to give an IOExtSer
  41.       structure which is completely blank execept for the io_SerFlags
  42.       field.
  43.  
  44.       The request structure's message and reply ports need not be
  45.       initialized.  The request structure is no longer needed after
  46.       the dio_open().
  47.  
  48.       returns NULL = error, else DIO descriptor (a pointer) returned.
  49.  
  50.  
  51.   dio_close(dfd)
  52.  
  53.       close an IO device.  Any pending asyncronous requests are
  54.       AbortIO()'d and then Wait'ed on for completion.
  55.  
  56.  
  57.   dio_closegrp(dfd)
  58.  
  59.       close EVERY DIO DESCRIPTOR ASSOCIATED WITH THE dio_open() call
  60.       that was the parent for this descriptor.    That is, you can get
  61.       a descriptor using dio_open(), dio_dup() it a couple of times,
  62.       then use dio_closegrp() on any ONE of the resulting descriptors
  63.       to close ALL of them.
  64.  
  65.  
  66.   dio_cact(dfd,bool)
  67.  
  68.       If an error occurs (io_Error field), the io_Actual field is usually
  69.       not modified by the device driver, and thus contains garbage.  To
  70.       provide a cleaner interface, you can have the DIO_CTL() and
  71.       DIO_CTL_TO() calls automatically pre-clear this field so if an
  72.       io_Error does occur, the field is a definate 0 instead of garbage.
  73.  
  74.       In most cases you will want to do this.  An exception is the
  75.       TIMER.DEVICE, which uses the io_Actual field for part of the timeout
  76.       structure.
  77.  
  78.       This flags the particular dio descriptor to do the pre-clear, and any
  79.       new descriptors obtained by DIO_DUP()ing this one will also have the
  80.       pre-clear flag set.
  81.  
  82.  
  83.   dio_dup(dfd)
  84.  
  85.       Returns a new channel descriptor referencing the same device. The new
  86.       descriptor has it's own signal and IO request structure. For
  87.       instance, if you openned the serial device, you might want to dup the
  88.       descriptor so you can use one channel to pend an asyncronous read,
  89.       and the other channel to write out to the device and do other things
  90.       without disturbing the asyncronous read.
  91.  
  92.  
  93.   sig = dio_signal(dfd)
  94.  
  95.       get the signal number (0..31) used for a DIO descriptor. This allows
  96.       you to Wait() for asyncronous requests.  Note that if your Wait()
  97.       returns, you should double check using dio_isdone()
  98.  
  99.  
  100.   req = dio_ctl_to(dfd, command, buf, len, to)
  101.  
  102.       Same as DIO_CTL() below, but (A) is always syncronous, and (B) will
  103.       attempt to AbortIO()+WaitIO() the request if the timeout occurs
  104.       before the IO completes.
  105.  
  106.       the 'to' argument is in microseconds.
  107.  
  108.       If timeout occurs before request completes, and DIO aborts the
  109.       request, some devices, such as the SERIAL.DEVICE do not have the
  110.       io_Actual field set properly.  Always check the io_Error field for
  111.       an abort before using io_Actual.
  112.  
  113.  
  114.   req = dio_ctl(dfd, command, buf, len)
  115.  
  116.       DIO_CTL() is the basis for the entire library.  It works as follows:
  117.  
  118.       (1) If the channel isn't clear (there is an asyncronous IO request
  119.       still pending), DIO_CTL() waits for it to complete
  120.  
  121.       (2) If the command is 0, simply return a pointer to the io
  122.       request structure.
  123.  
  124.       (3) If the DIO_CACT() flag is TRUE, the io_Actual field of the
  125.       request is cleared.
  126.  
  127.       (4) Set the io_Data field to 'buf', and io_Length field to 'len'
  128.       If the command is positive, use DoIO().  If the command
  129.       negative, take it's absolute value and then do a SendIO().
  130.       (The command is placed in the io_Command field, of course).
  131.  
  132.       (5) return the IO request structure
  133.  
  134.  
  135.   bool= dio_isdone(dfd)
  136.  
  137.       return 1 if current channel is clear (done processing), else 0. e.g.
  138.       if you did, say, an asyncronous read, and dio_isdone() returns true,
  139.       you can now use the data buffer returned and look at the io_Actual
  140.       field.
  141.  
  142.       You need not do a dio_wait() after dio_isdone() returns 1.
  143.  
  144.  
  145.   req = dio_wait(dfd)
  146.  
  147.       Wait on the current channel for the request to complete and then
  148.       return the request structure. (nop if channel is clear)
  149.  
  150.  
  151.   req = dio_abort(dfd)
  152.  
  153.       Abort the request on the current channel (nop if channel is
  154.       clear).  Sends an AbortIO() if the channel is active and then
  155.       WaitIO()'s the request.
  156.  
  157.     ------ MACROS ------
  158.  
  159.     dio_simple() and related macros return the !io_Error field. That
  160.     is, 0=ERROR, 1=OK
  161.  
  162.     dio_actual() returns the io_Actual field instead of !io_Error.
  163.  
  164.     NOTE: the io_Actual field may not be set by the device if an
  165.     error condition exists.  To make the io_ctl() and io_ctl_to()
  166.     call automatically clear the io_Actual field before doing the
  167.     io operation, use the DIO_CACT() call.  The reason this isn't
  168.     done automatically by default is that some devices require
  169.     parameters to be passed in the io_Actual field (like the
  170.     timer.device).
  171.  
  172.     Remember, Asyncronous IO is done by sending -com instead of com.
  173.     (that is, negative command).
  174.  
  175.       CALL              Syncronous IO   Asyncronous IO
  176.  
  177.   dio_simple(dfd,com)             0=ERROR, 1=OK   undefined
  178.   dio_actual(dfd,com)             io_Actual       undefined
  179.   dio_reset(dfd)                  0=ERROR, 1=OK   n/a
  180.   dio_update(dfd)                 0=ERROR, 1=OK   n/a
  181.   dio_clear(dfd)                  0=ERROR, 1=OK   n/a
  182.   dio_stop(dfd)                   0=ERROR, 1=OK   n/a
  183.   dio_start(dfd)                  0=ERROR, 1=OK   n/a
  184.   dio_flush(dfd)                  0=ERROR, 1=OK   n/a
  185.   dio_getreq(dfd)                 returns a ptr to the IO
  186.                   request structure
  187.  
  188.       NOTE: If you use the following, you probably want to have the device
  189.       library automatically clear the io_Actual field before sending the
  190.       request so you get 0 if an error occurs.    That is: dio_cact(dfd,1):
  191.  
  192.   dio_read(dfd,buf,len)           returns actual bytes read
  193.   dio_write(dfd,buf,len)          returns actual bytes written
  194.  
  195.     The timeout argument for dio_readto() and dio_writeto()
  196.     is in MICROSECONDS, up to 2^31uS.
  197.  
  198.   dio_readto(dfd,buf,len,to)      returns actual bytes read
  199.   dio_writeto(dfd,buf,len,to)     returns actual bytes written
  200.  
  201.     The asyncronous dio_reada() and dio_writea() do not
  202.     return anything.
  203.  
  204.   dio_reada(dfd,buf,len)          begin asyncronous read
  205.   dio_writea(dfd,buf,len)         begin asyncronous write
  206.  
  207.  
  208.  
  209.  
  210.  
  211. \Rogue\Monster\
  212. else
  213.   echo "will not over write ./dio.doc"
  214. fi
  215. if [ `wc -c ./dio.doc | awk '{printf $1}'` -ne 6534 ]
  216. then
  217. echo `wc -c ./dio.doc | awk '{print "Got " $1 ", Expected " 6534}'`
  218. fi
  219. if `test ! -s ./qint.doc`
  220. then
  221. echo "writing ./qint.doc"
  222. cat > ./qint.doc << '\Rogue\Monster\'
  223.  
  224.                QINT DOCUMENTATION
  225.  
  226.         Matthew Dillon
  227.  
  228.         dillon@ucbvax.berkeley.edu    ARPA
  229.         ...!ihnp4!ucbvax!dillon    USENET
  230.  
  231. NOTE!!!!!   Lattice Users must replace the 'jsr _geta4' call with the
  232.         appropriate call to retrieve the address register for the
  233.         small data model before compiling!    You might have to make
  234.         other modifications as well (I don't know since I don't
  235.         have Lattice).
  236.  
  237.  
  238. The Calls:
  239.     char oldpri;        range -128 to 127
  240.     char newpri;
  241.     char pri;
  242.     long signum;        0 .. 31
  243.  
  244.     void (*vector)();   function vector returning nothing
  245.     void (*oldvec)();
  246.  
  247.  
  248.     While active Q interrupt vectors exist, the tc_ExceptCode in the
  249.     task structure will be modified.  The old tc_ExceptCode is used if
  250.     an unknown exception occurs (one that is not a Q interrupt).
  251.  
  252.     oldpri = SetQPri(newpri)
  253.  
  254.     Set the task's current Q priority.  Any Q interrupts of lower or
  255.     equal priority that occur will be queued until the priority is
  256.     dropped sufficiently.
  257.  
  258.     The initial task priority is -128 (essentially allowing all Q
  259.     interrupts -127 to 127 to occur).
  260.  
  261.     oldvec = SetQVector(signum, vector, arg, pri)
  262.  
  263.     If vector is non-null, enables the exception at the specified
  264.     priority (-127 to 127).  specified vector is called in a C
  265.     compatible way with one user argument (arg).  Specifying a
  266.     priority of -128 does not make sense because this is the lowest
  267.     allowed priority and the Q interrupt will thus never occur.
  268.  
  269.     If vector is null, the exception and Q interrupt is disabled.
  270.     After the last Q interrupt is removed, tc_ExceptCode is restored
  271.     to its original value.
  272.  
  273.  
  274. BUGS:
  275.     The only bug that I know of is a problem with EXEC.
  276.  
  277.     What is Good:    An exception will not occur while one is Forbid()n
  278.     What is Bad:    If an exception comes in while Forbid()n, it will
  279.             NOT be immediately entered when you Permit().
  280.  
  281.     Whoops.  The exception *will* occur when EXEC next checks its
  282.     signals and exceptions, which occurs on the obvious EXEC library
  283.     calls (SetExcept(), SetSignal(), etc...)  and perhaps Wait().
  284.  
  285.     In most cases you can ignore the problem.
  286.  
  287.  
  288. GENERAL WORKINGS OF Q INTERRUPTS:
  289.  
  290.     If you know how EXEC signals and the 68000 interrupt structure
  291.     works, then you know how Q interrupts work.  Simply replace
  292.     "processor" with "task" and "0-7" with "-128 to 127" for task
  293.     Q interrupt priorities (this is different from the Task's
  294.     scheduler priority).
  295.  
  296.     Q interrupts work just like 68000 interrupts.  If the task is
  297.     currently running at a Q interrupt priority N, only Q interrupts
  298.     of HIGHER priority can occur.  Q interrupts of LOWER OR EQUAL
  299.     priority are queued and will occur as soon as the priority is
  300.     lowered.  Everything occurs in priority order, the highest priority
  301.     pending interrupt is always the one running (or the task's main
  302.     routine if it has the highest priority).
  303.  
  304.     Thus, while a Q interrupt handler is running at some specific
  305.     priority, other Q interrupts at the same priority will wait
  306.     until the first one finishes and then execute in a FIFO fashion.
  307.  
  308. THE INTERRUPT VECTOR ROUTINE:
  309.  
  310.     A specific Q interrupt vector is a C subroutine called with one
  311.     longword argument (that specified when you SetQVector()'d it).
  312.     This works fine with the small model.
  313.  
  314.     The handler runs with all normal EXEC processing enabled, and in
  315.     the context of its task.  It can be viewed almost as a subroutine
  316.     call from the task.  However, you must be careful about the
  317.     reentrancy of certain functions.  STDIO, DOS, and many other
  318.     library calls are not reentrant, and you must use SetQPri() to
  319.     ensure such calls are not interrupted.    NOTE that you CAN mix
  320.     certain calls.    I don't have much info on what combinations work,
  321.     but certainly most library calls that do not depend on being
  322.     called singularly from tasks will work (for example, GetMsg()).
  323.     And, of course, if all your handler does is make some small
  324.     calculations this can interrupt anything.
  325.  
  326.     If you cause an exception (the same exception) from within the
  327.     handler, it will be remembered.  (That is, the signal is cleared
  328.     before the handler is called), and occur after your handler
  329.     returns.
  330.  
  331. USES FOR Q INTERRUPTS:
  332.  
  333.     Use #1:     To be able to execute menu options which do not effect
  334.             the 'current' operation.  E.G. if you are doing a
  335.             ray tracing you could make the intuition window's
  336.             signal bit a Q interrupt and handle Intuition messages
  337.             that way....   The main loop generating the ray
  338.             tracing would not have to continuously check for
  339.             Intuition messages.
  340.  
  341.     Use #2:     Lets say you are writing a terminal program and want
  342.             to display data comming in smoothly while sending a
  343.             file.  While this can be done easily with the
  344.             asynchronous ability of IO devices, it would be even
  345.             easier if you handled the receive with a Q interrupt...
  346.             that way, you could display received data (SendIO to
  347.             the console device) even if the file sender is in
  348.             the middle of a DOS call to read the next file block.
  349.  
  350.     Many more uses (I hope!).
  351.  
  352.                 -Matt
  353.  
  354.  
  355. \Rogue\Monster\
  356. else
  357.   echo "will not over write ./qint.doc"
  358. fi
  359. if [ `wc -c ./qint.doc | awk '{printf $1}'` -ne 4986 ]
  360. then
  361. echo `wc -c ./qint.doc | awk '{print "Got " $1 ", Expected " 4986}'`
  362. fi
  363. if `test ! -s ./summary.doc`
  364. then
  365. echo "writing ./summary.doc"
  366. cat > ./summary.doc << '\Rogue\Monster\'
  367.  
  368. SUMMARY.DOC    Summary of library functions
  369.  
  370.  
  371.             -------- ASYNCHRONOUS FILE SUPPORT --------
  372.  
  373.  
  374.     xfi =   xfopen(file, mode, bytes)       mode: r-read w-write w+-append
  375.     err =   xfclose(xfi)
  376.      n    =   xfread(xfi, buf, n)             0 on EOF/error
  377.      n    =   xfgets(xfi, buf, max)           -1 on EOF/error else string length
  378.     err =   xfwrite(xfi, buf, n)
  379.  
  380.         bmov(src,dest,bytes)
  381.         bcmp(src,dest,bytes)
  382.         bset(src, bytes, c)
  383.         bzero(src, bytes)
  384.  
  385.         checkbreak()
  386.         resetbreak()
  387.         disablebreak()      (not available as a run-time library call)
  388.         enablebreak()       (not available as a run-time library call)
  389.  
  390.         openlibs(flags)
  391.         closelibs(flags)
  392.         closelibs(-1)       close all libraries openned w/ openlibs()
  393.  
  394.      bool = wildcmp(wildstr, namestr)
  395.  
  396.         mountrequest(bool)
  397.  
  398.         fhprintf(fh, ctrlstr, args...)
  399.  
  400.         llink(list, en)         (OBSOLETE)
  401.         lunlink(en)             (OBSOLETE)
  402.  
  403.                 SYSTEM SUPPORT
  404.  
  405.      port = CreateUniquePort(name, priority)    create port w/unique name
  406.         DeleteUniquePort(port)              delete port w/unique name
  407.         PutSyncMsg(port, msg)               normal synchronous message
  408.         PutSyncMsgSimple(port, ptr, cmd)    simple synchronous message
  409.    retcmd = WaitMsg(msg)                        wait for message to come back
  410.         CheckMsg(msg)                       check if message has come back
  411.         GetHead(list)
  412.         GetTail(list)
  413.         NextNode(node)
  414.  
  415.                   IO SUPPORT
  416.  
  417.       dfd = dio_open(name, unit, flags, req/NULL)
  418.         dio_close(dfd)
  419.         dio_closegrp(dfd)
  420.         dio_cact(dfd,bool)
  421.         dio_dup(dfd)
  422.       sig = dio_signal(dfd)
  423.       req = dio_ctl_to(dfd, command, buf, len, to)
  424.       req = dio_ctl(dfd, command, buf, len)
  425.       bool= dio_isdone(dfd)
  426.       req = dio_wait(dfd)
  427.       req = dio_abort(dfd)
  428.  
  429.         also a large array of macros are available.  if command < 0, then
  430.         asyncronous execution is implied.  Macros:
  431.  
  432.                         SYCHRONOUS        ASYNCHRONOUS
  433.  
  434.         dio_simple(dfd,com)             0=ERROR, 1=OK   undefined
  435.         dio_actual(dfd,com)             io_Actual       undefined
  436.         dio_reset(dfd)                  0=ERROR, 1=OK   n/a
  437.         dio_update(dfd)                 0=ERROR, 1=OK   n/a
  438.         dio_clear(dfd)                  0=ERROR, 1=OK   n/a
  439.         dio_stop(dfd)                   0=ERROR, 1=OK   n/a
  440.         dio_start(dfd)                  0=ERROR, 1=OK   n/a
  441.         dio_flush(dfd)                  0=ERROR, 1=OK   n/a
  442.         dio_getreq(dfd)                 returns a ptr to the IO request structure
  443.         dio_read(dfd,buf,len)           returns actual bytes read
  444.         dio_write(dfd,buf,len)          returns actual bytes written
  445.  
  446.         dio_readto(dfd,buf,len,to)      returns actual bytes read
  447.         dio_writeto(dfd,buf,len,to)     returns actual bytes written
  448.  
  449.         dio_reada(dfd,buf,len)          begin asyncronous read
  450.         dio_writea(dfd,buf,len)         begin asyncronous write
  451.  
  452.  
  453. \Rogue\Monster\
  454. else
  455.   echo "will not over write ./summary.doc"
  456. fi
  457. if [ `wc -c ./summary.doc | awk '{printf $1}'` -ne 2888 ]
  458. then
  459. echo `wc -c ./summary.doc | awk '{print "Got " $1 ", Expected " 2888}'`
  460. fi
  461. if `test ! -s ./suplib.doc`
  462. then
  463. echo "writing ./suplib.doc"
  464. cat > ./suplib.doc << '\Rogue\Monster\'
  465.  
  466. SUPLIB.DOC    General C Support Library
  467.  
  468.                 COMPILATION
  469.  
  470.     Compile all modules using a precompiled symbol table of all the
  471.     AMIGA include's (*/*.H) ... do *NOT* include standard aztec
  472.     includes (stdio.h, etc...).  The Makefile for the precompiled symbol
  473.     table is in the LOCAL directory.
  474.  
  475.     You must use the +L option (32 bit ints) for ALL COMPILATIONS, including
  476.     the generation of the symbol table when compiling SUPLIB (SUP32.LIB).
  477.     Also, use +B (no .begin reference), +CD (large code and data) model
  478.     when compiling this source.
  479.  
  480.  
  481.                     MODULES
  482.  
  483.     QINT:    These are exception based prioritized software interrupt
  484.         routines.  see QINT.DOC
  485.  
  486.     ASYNCOP:    Asynchronous function execution.  Make asynchronous
  487.         function calls (not incredibly fast).
  488.  
  489.     XFIO:    Asyncronous file IO.  Allows sequential asyncronous access
  490.         to files for both reading (reads ahead asyncronously) and
  491.         writing (writes asyncronously).  Usually employed by CPU
  492.         bound programs not wishing to be slowed down even more by
  493.         the disk.  Extremely useful for implementation of capture
  494.         and serial protocols.
  495.  
  496.     DIO:    Device IO package.  This is a Generic interface for handling
  497.         the Amiga's EXEC devices.  It makes your code smaller and
  498.         much easier to read.  You no longer need to be a guru to
  499.         use devices.
  500.  
  501.     BSTRING:    memory move/set/compare routines.  Operations are done in
  502.         longwords when possible.
  503.  
  504.     SYS:    System enhancement calls
  505.  
  506.     MISC:    misc. routines (break checking, openning/closing libraries),
  507.         date and time routines, setfiledate, etc...
  508.  
  509.  
  510.     ---------------------------------------------------------------------
  511.  
  512.                    QINTS
  513.  
  514.     SEE QINT.DOC
  515.  
  516.  
  517.                   ASYNCH OP
  518.  
  519. handle= NewAsyncOp()
  520.  
  521.     Create a new task for handling asynchronous function calls.
  522.  
  523. (void)  StartAsyncOp(handle, func, arg1, arg2, arg3)
  524.  
  525.     Queue up a function for the handle.  Multiple functions may
  526.     be queueud.  NOTE:  The registers A4 and A5 will be initialized
  527.     to what they were when NewAsyncOp() was called.
  528.  
  529.     The function must preserve D4-D7/A2-A3.  D0-D3/A0-A1/A4-A6 may
  530.     be destroyed by the function.
  531.  
  532.  
  533. bool  = CheckAsyncOp(handle, n)
  534.  
  535.     Return TRUE if a minimum of N async operations started with
  536.     StartAsyncOp() have completed, FALSE otherwise.  The number
  537.     of async operations in progress is the number started minus
  538.     the number already waited for.
  539.  
  540. (void)= WaitAsyncOp(handle, n)
  541.  
  542.     Wait for N of the operations in progress to complete.  -1 can
  543.     be specified to wait for ALL the operations in progress to
  544.     complete.
  545.  
  546.     For example, if you queue up 3 commands, CheckAsyncOp(handle, 3)
  547.     will check if all 3 have completed, and WaitAsyncOp(handle, 3)
  548.     waits and removes their reply messages as well as adjusts the
  549.     number of 'operations in progress' to 0.
  550.  
  551.     I.E, if you were to WaitAsyncOp(handle, 2) instead of 3, after
  552.     it returns there will be 1 operation in progress left.    If you
  553.     were to do another StartAsyncOp(), there would now by 2 in
  554.     progress.
  555.  
  556. (void)  CloseAsyncOp(handle)
  557.  
  558.     Wait for all operations in progress to end (WaitAsyncOp(handle,-1)),
  559.     then remove the task.
  560.  
  561.                  XFIO
  562.  
  563.  
  564.     xfi =   xfopen(file, mode, bytes)
  565.     err =   xfclose(xfi)
  566.      n    =   xfread(xfi, buf, n)
  567.      n    =   xfgets(xfi, buf, max)
  568.     err =   xfwrite(xfi, buf, n)
  569.  
  570.         mode is "r", "w", or "w+".  No seeking is allowed as you can
  571.         see.  If you openned for reading, you may NOT use xfwrite(),
  572.         and if you openned for writing, you may NOT use xfread().
  573.  
  574.         r   read
  575.         w   write-newfile
  576.         w+  write-append
  577.  
  578.         The specified buffer size (bytes) is used to create two
  579.         buffers of (bytes/2) bytes, double buffering either
  580.         asyncronous read ahead, or asyncronous writes.
  581.  
  582.         'err' returns 1 if a write error occured.  err is returned
  583.         by xfclose() (xfclose() waits for any asyncronous writes
  584.         to complete and thus can return whether they failed or not).
  585.         Once set, err stays set forever.
  586.  
  587.         XFREAD: 0 is returned on EOF or error
  588.         XFGETS: the length of the string is returned.  0 is a valid
  589.             length (a blank line).  -1 is returned on EOF or
  590.             error.    The newline is removed and a string
  591.             terminator (0) added.
  592.  
  593.  
  594.                 DIO
  595.  
  596.      SEE DIO.DOC
  597.  
  598.  
  599.                    BSTRING
  600.  
  601. (void)  bmov(src,dest,bytes)
  602. bool  = bcmp(src,dest,bytes)
  603. (void)  bset(src, bytes, c)
  604. (void)  bzero(src, bytes)
  605.  
  606.     These functions do various memory operations.  bcmp() is does an
  607.     unsigned comparison, of course.  bcmp() only checks for
  608.     equivalence, returning TRUE (1) if the buffers are the same,
  609.     FALSE (0) otherwise.  bcmp() uses longword compares when possible.
  610.  
  611.     bmov() does an ascending or decending copy as appropriate.
  612.     bmov(), bzero(), and bset() use longword and MULTIPLE REGISTER
  613.     operations when possible.
  614.  
  615.     These functions are the same as the BSet(), BZero(), BMov(), and
  616.     BCmp() in my run-time library DRES.LIBRARY.
  617.  
  618. bool =    checkbreak()
  619.  
  620.     Check whether the process has received a ^C or ^D signal.  ^D
  621.     is also checked here allowing a more reliable break-mechanism,
  622.     as Aztec and Lattice stdio routines will clear ^C even when
  623.     break is disabled.
  624.  
  625. (void)  resetbreak()
  626. (void)  disablebreak()
  627. (void)  enablebreak()
  628.  
  629.     resetbreak() clears both the ^C and ^D signals.  disablebreak()
  630.     and enablebreak() modify the global variable Enable_Abort and
  631.     thus stdio's automatic break detection/abort.
  632.  
  633.  
  634. bool  = openlibs(flags)
  635. bool  = closelibs(flags)
  636.  
  637.     See the flag definitions in XMISC.H.  openlibs() opens all
  638.     specified libraries, returning 0 if one or more could not
  639.     be openned.  closelibs() closes all specified libraries.
  640.     openlibs() does not open a library that is already open (if you
  641.     make the call more than once), and simply uses the already
  642.     open descriptor.
  643.  
  644.     closelibs(-1) closes ALL libraries openned with openlibs(), but
  645.     NOT libraries openned otherwise.
  646.  
  647.     Note that you cannot open or close DOS or EXEC.  This is because
  648.     the C startup will do this for you, and also to prevent linker
  649.     warning messages.
  650.  
  651. Window= GetConWindow()
  652.  
  653.     This functions retrieves the struct Window * from the console
  654.     device associated with this process.  NULL is returned if the
  655.     window could not be found (still, operation may not be dependable
  656.     if the process's console is not a console device).
  657.  
  658. buf   = datetos(date, buf, ctl)
  659.     DATESTAMP *date;
  660.     char *buf;
  661.     char *ctl;
  662.  
  663.     This function converts a DOS DateStamp structure into a string
  664.     and places it in the specified buffer.    ctl specifies the format
  665.     of the date by pieces (ctl can be NULL, indicating "D M Y h:m:s").
  666.  
  667.     If not NULL, ctl is a string containing combinations of the
  668.     following characters.  Spacing must also be specified.    Any
  669.     unrecognized characters are passed to the output buffer verbatim.
  670.  
  671.         D    The day     23
  672.         M    The month    Jul
  673.         Y    The year    1988
  674.         h    The hour    03
  675.         m    The minute    23
  676.         s    The seconds    04
  677.  
  678.     This function is equivalent to DateToS() in my run time library
  679.     DRES.LIBRARY
  680.  
  681. (void)  llink(list, en)         (OBSOLETE)
  682. (void)  lunlink(en)             (OBSOLETE)
  683.  
  684.     see XMISC.H .  Simple doubly-linked list routines.  XLIST is both
  685.     the list base and an element.  The list base should be initialized
  686.     to zero before use.
  687.  
  688. (void)  mountrequest(bool)
  689.  
  690.     enable or disable the DOS requester which comes up when you attempt
  691.     to open a path not currently mounted.  Normal mode is TRUE (1),
  692.     meaning that you get the requester.  This routine remembers the
  693.     previous contents of pr_WindowPtr.  The call mountrequest(0) may
  694.     be made multiple times and then mountrequest(1) will restore the
  695.     original contents of pr_WindowPtr.
  696.  
  697. RemSemaphore()
  698. FindSemaphore()     (SEE EXEC DOCUMENTATION FOR CALLING PARAMETERS)
  699. AddSemaphore()
  700.  
  701.     These functions fix the broken bindings in older Lattice and
  702.     Aztec libraries.
  703.  
  704. bool  = setfiledate(file, date)
  705.     char *file;
  706.     DATESTAMP *date;
  707.  
  708.     This function implements the new ACTION_SET_DATE packet and
  709.     sets the timestamp of a file.  You cannot set the timestamp
  710.     for the root of a filesystem with this call.
  711.  
  712.     This function is equivalent to the SetFileDate() function in
  713.     DRES.LIBRARY.
  714.  
  715. bool =    wildcmp(wildstr, namestr)
  716.  
  717.     compare the wildcard string (containing '*'s and '?'s) with
  718.     the file name (namestr) and return TRUE (1) if they compare,
  719.     and FALSE (0) otherwise.
  720.  
  721.     This function is equivalent to the WildCmp() function in
  722.     DRES.LIBRARY.
  723.  
  724. (void)  fhprintf(fh, ctrlstr, args...)
  725.  
  726.     uses the EXEC formatted printing call to format text and then
  727.     writes it to an AMIGADOS file handle.
  728.  
  729.  
  730. rval  = AutoAllocMiscResource(resno, value)
  731.  
  732.     resno: MR_SERIALPORT, SERIALBITS, PARALLELPORT, or PARALLELBITS
  733.     value:    -1 to allocate, 0 to check.
  734.  
  735.     This functions allocates or checks the specified resource.  0
  736.     (ZERO) is returned on SUCCESS (allocated or could allocate),
  737.  
  738.     NON-ZERO is returned if the resource is already allocated by
  739.     somebody else.
  740.  
  741. (void)= AutoFreeMiscResource(resno)
  742.  
  743.     Free's a resource you allocated.  YOU MUST OWN THE RESOURCE!
  744.  
  745.     Neither of these functions require you to open the misc.resource
  746.     resource.
  747.  
  748. font  = GetFont(name, ysize)
  749.  
  750.     This function searches both memory and the disk for the requested
  751.     font, and automatically opens/closes the diskfont library if it is
  752.     not already open.  It opens the font, incrementing the reference
  753.     count.
  754.  
  755. (void)  InitDeemuNW(ary, nw)
  756.     short *ary;
  757.     NW *nw;
  758.  
  759.     ary points to the 'NW','  ' Deemu[] array entry.  The NewWindow
  760.     structure is initialized according to the Deemu entry.    Currently,
  761.     TopEdge, LeftEdge, Width, Height, DetailPen and BlockPen will
  762.     be initialized... less if the Deemu entry contains less information.
  763.  
  764. char   *GetDEnv(name)
  765.     char *name;
  766.  
  767.     Return a string to the enviroment variable name, returning NULL
  768.     if it does not exist.
  769.  
  770. bool    SetDEnv(name, str)
  771.     char *name, *str;
  772.  
  773.     Set the enviroment variable name to the string str.  Return C-TRUE
  774.     (1) on success, or C-FALSE (0) on failure.
  775.  
  776.  
  777.  
  778. \Rogue\Monster\
  779. else
  780.   echo "will not over write ./suplib.doc"
  781. fi
  782. if [ `wc -c ./suplib.doc | awk '{printf $1}'` -ne 9714 ]
  783. then
  784. echo `wc -c ./suplib.doc | awk '{print "Got " $1 ", Expected " 9714}'`
  785. fi
  786. echo "Finished archive 1 of 1"
  787. # if you want to concatenate archives, remove anything after this line
  788. exit
  789. -- 
  790. Bob Page, U of Lowell CS Dept.  page@swan.ulowell.edu  ulowell!page
  791. Have five nice days.
  792.